home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 2.toast / pc / sample code / overview / dtscpluslibrary / documents / asserts < prev    next >
Encoding:
Text File  |  2000-06-23  |  5.1 KB  |  79 lines
  1.  
  2. .c.INTRODUCTION 
  3. The core idea behind using asserts is to specify a condition, and trigger an event based on the case where the condition is false. In other words we assume that everything is OK, but if this is not the case, we want to signal the problem.
  4.  
  5. This simple concept is very powerful concerning debugging and testing. The more asserts we place into our code, the more sure we are about states, and what is going on inside the application.
  6.  
  7. The core problem with asserts is usually either laziness to implement these, or the worry that the application will slow down too much due to assert functions[1], or then there’s no coherent way of defining asserts.
  8.  
  9. Now, ANSI C libraries has a function called assert() that will take a statement and error. However we want to have a much better control of what is happening when an assert is triggered. For instance, we would like to drop to a high level or a low level debugger, log it into a file, maybe present a power-user Alert with low level information that could be sent back to the developer during an alpha/beta test, or maybe even forward the information to another process or machine using Apple Events.
  10.  
  11. .c.ASSERT Macros
  12. A set of assert macros in the DTSC++Library.h is addressing this need.  The use of these macros are very straight forward:
  13.  
  14.     fError = ::AESend(&fAE, &fReply, fSendMode, fPriority, fTimeout,         nil, nil);
  15.     ASSERT(fError == noErr, ("\pProblems with AESend = %d");
  16.  
  17. or 
  18.     fError = ::AESend(&fAE, &fReply, fSendMode, fPriority, fTimeout,         nil, nil);
  19.     VASSERT(fError == noErr, ("Problems with AESend = %d", fError));
  20.  
  21. The ASSERT takes two arguments, a statement that should evaluate to true, if false it will print out a message (Str255) defined in the second parameter. 
  22.  
  23. VASSERT has also a condition in the first parameter, and accepts printf style variable arguments in the second parameter. Note that we are using C style, or actually printf style definitions instead of Str255s[2] . Note also that we need to place this statement inside parenthesis because VASSERT will expand to a macro, and unless we clearly mark that this whole block is one single part, we will end up in trouble.
  24.  
  25.  
  26. .c.Labels
  27. We have the following labels defined inside the header file:
  28.  
  29. // GLOBAL DEFINITIONS
  30.  
  31. // TESTING, used for flagging that we use test code inside the classes and frameworks
  32. // TESTLEVEL0     - user friendly alerts as part of the application
  33. // TESTLEVEL1     - minor test level (detailed error message in alert //              box)
  34. // TESTLEVEL2     - semi-major test level (high level debuggers)
  35. // TESTLEVEL3     - major test level (low level debuggers)
  36. // TESTLOG1        - trigger a file log of information
  37. // TESTLOG2        - trigger a file log of information from a low level //              debugger
  38.  
  39. #define TESTLEVEL3
  40.  
  41.  The core idea is that a developer will specify how asserts will be printed. If none of these labels are defined, then both macros will expand to ((void 0), in other words no code.
  42.  
  43. TESTLEVEL0 could be defined as a user friendly alert that either terminates the program with a friendly message, or otherwise does something that is part of the friendly look and feel of a Macintosh.
  44.  
  45. TESTLEVEL1 will trigger an alert box with the message stated in the ASSERT part. This level could be used to create alpha/beta level applications that could be sent to end user testers, and they could dutifully report the messages back to the developer.
  46.  
  47.  
  48. TESTLEVEL2 will trigger a break into a high level debugger (SADE, SourceBug). In other words we are using SysBreakStr. Note that the Think debugger hates this trap (crashes), as well as the machine usually crashes if not high level debugger is running., so be careful. In the case of Think, use:
  49.  
  50. TESTLEVEL3 will trigger a break into a low level debugger, we are using DebugStr. In the case of ASSERT we will drop directly into the next executable line. In the case of VASSERT we are not that lucky, because due to va_arg use for variable argument parsing VASSERT is calling various libraries, and we end up further down the chain of functions.
  51.  
  52. TESTLOG1 will define that we will print an entry into a file placed on the top level of the boot volume, with a time/date stamp.
  53.  
  54. TESTLOG2 will additionally do a low level debugger dump of the current register use, calling chain of functions and the currently executed instructions.
  55.  
  56.  
  57. .c.Other Flags
  58. The FILEINFO flag defines if we want to add file/line information to the message. This information is taken from the __FILE__ and __LINE__ ANSI definitions. By default this flag is enabled.
  59.  
  60. .c.Source Code
  61. The macros are defined in the DTSC++Library.h file.
  62.  
  63. .c.Future Enhancements
  64. We are open for suggestions, one direction is to create a feature flagged with TESTAELOG that will send out Apple Events with the string attached to. This would make it possible to log the information into another process residing either inside the same Mac, or over the network to another system.
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77. [1] This was one of the major reasons the early Eiffel compilers got a bad reputation, because asserts were turned on by default for the final builds :-)
  78. [2] We would have used C strings in ASSERT as well, but Think C does not have debugstr implemented, sigh…
  79.